End of OPW

Today is the last official day of OPW, but certainly not my last day with OpenMRS. It’s been a whirlwind summer and I can’t believe it’s already over. School has started back up for me, so the past few weeks haven’t been as tangibly productive as I would have liked. I have had a lot of time for reflection on this amazing opportunity I’ve had to work in the F/LOSS community. Here are  few parting thoughts for this blog:

• Gender: I have such respect for the work of OPW to make women, gender-queer, and non-male-identifying people feel welcome in the world of technology. It’s definitely been a challenge for me to recognize the ability in myself to break down gender norms in tech. I’ve often been afraid to assert myself, to apply for things, to recognize my own skills and abilities. I’m sure a lot of this has to do with my own internalized, subconscious ideas about myself and my gender. (Imposter syndrome anyone?). I cannot begin to explain how incredible it is to have an opportunity like OPW empower me to have the confidence to compete in a male-dominated field.
• Community: I’ve fallen in love with the community element of open source. From IRC to wikis, having a framework of people who all care about, develop and use the same product is amazing. I’ve never experienced software in such a personal way. I never know software could be personal. My relationship with the software I interact with has always been indifferent and clinical. Now, I don’t just see and interact with a piece of software, I see and interact with the community behind it.
• Future: I’m not ready to stop here. I want to spread the word about the power of F/LOSS, and the potential for everyone to be involved- regardless of gender. I’ll be sticking around OpenMRS to work on documentation, and I’m forwarding OPW information to every lady I know. I just got an OpenMRS sticker in the mail and it’s proudly on display on my laptop case. [I’m just sitting here waiting for someone to ask me about it.] It’s a testament to my incredible summer, and the incredible future ahead of me.

Thanks to everyone involved in OPW.  You’ve positively impacted me in ways I cannot begin to describe. Keep up the amazing work.

GSOC Doc Camp!

Exciting news! OpenMRS has been accepted to attend the 2013 Google Docs Camp,  and I’ll be one of the representatives. The docs camp is set up as a conference on free software documentation, and a hands-on production platform for attending organizations to write FLOSS manuals. We’re going to be concentrating specifically on updating and (re)writing guides for new developers. The conference takes place in California in October.

As we’re nearing the end of OPW, it’s so exciting for me to know that my work with OpenMRS will be continuing even after my internship is over.  Most exciting of all, I was contacted this week by someone interested in volunteering to write documentation for OpenMRS. I explained everything that we’re in the process of doing: sorting module pages, updating module pages, creating stub pages*, getting community feedback and input**, and finalizing the style and template guides***. I linked this person to the template and style guide to help them get started and I’m so pleased to know that my work is being put to use.

I’m happy to say that one of the original goals of the summer, sustainability, is being realized. Not only have I created useful ‘meta-documentation’ for future documentors (which is already being used!), but I myself am certainly staying around to help out with OpenMRS documentation even after OPW.

*This is a new task. A lot of modules exist in the repository, but don’t actually have a corresponding wiki page. The repository doesn’t really contain any documentation, just a short overview and a download link. As such, for each module that exists in the repository but not on the wiki, I’ve been creating a ‘stub’ page with just the module name, overview and download link. Once all stub pages have been created, we’ll start filling them in with information.

**A lot of great things have come out of sorting and commenting on each module page. Many people have provided great feedback, and even started updating their documentation pages.

***I’ve updated these so that they’re not just a guide but a reflection of the documentation. For example, the table of contents is an actual table of contents with hyperlinks, there are screen shots and example diagrams and links, etc. Check it out! https://wiki.openmrs.org/display/~evoeges/Documentation+Style+Guide

Update from the World of Docs

A lot has happened these past two weeks, most of it revolving around opening up my current work to the OpenMRS community for review, feedback and critique. I also met Ellen Ball, one of my mentors! It was great to see her in person and put a face to all of our email/IM/video/voice conversations.

I finished the Style Guide- it includes a section for conceptual writing tips (such as layout, style, etc) and a section for technical writing tips (spelling, punctuation, etc). A lot of the information for this guide came from reading through style guides for other organizations (especially GNOME and Atlaissan.) The guide’s rough draft is available here:
https://wiki.openmrs.org/display/~evoeges/Documentation+Style+Guide.
It’s ready and waiting for feedback!

I also updated the module documentation template, adding a few more sections (Ownership- who can be contacted to discuss the module? FAQ, and where to direct further questions) and altering a few others (the beginner explanation is now ‘How it Works’ and the advanced explanation is now ‘Technical Explanation’). A lot of great feedback has been coming in, so I’ll be updating it again this week and tweaking it based on suggestions.

I’m still sorting through the current documentation and labelling based on the level of work each page needs. Labels for pages are Red, Yellow and Green and pages can be aggregated based on their labels for easy organization.
https://wiki.openmrs.org/display/~evoeges/Sorting+Current+Documentation.
I’m also trying to add comments to pages to explain what I think most needs to be improved.

Upcoming: the first implementation of the Documentation Template! As I sort through pages, I’m on the lookout for a good page(s) to update to the Template and use as example documentation pages.

GUADEC 2013: Learning from Another FLOSS Project

This week is the GNOME User And Developer European Conference [GUADEC], an annual conference held (this year) in Brno, Czech Republic. I’m here meeting the OPW organizers (the Outreach Program for Women is part of the GNOME Foundation) and other interns, and attending some fantasically informative and interesting talks.

I’ve been attending talks that are oriented for new developers (“Put Your GNOME foot forward”; “Newcomer’s Workshop”, “FLOSS Community Outreaches”) to learn about how another FLOSS project handles outreach and newcomers (and learning how to make contributions to GNOME myself!). A lot of great tips and advice that are more than applicable to OpenMRS have surfaced, and many things that can be incorporated into the New Developer Guide, which I’ll be revamping in the coming weeks.

• “start with your favourite applications, start small.” For OpenMRS, start with your favourite modules! Start simple.
• “read wiki pages and documentation.” Maybe even contribute to the wiki pages and documentation, as a starting point to learn about OpenMRS and join the community.
• “keep track of things for yourself; make a checklist, keep a blog, update your personal wiki page.” Keeping your personal wiki updated is a great way to keep everyone in the community up to date on what you’re doing
• “work with the community, not against it.”

I’m also looking forward to attending talks specific to documentation (tomorrow, “Documentation: State of the Union”) and a talk specifically about OPW.

Apart from that, I’ve been continuing my work from last week and have my first simple infographic. I decided to go with something that wouldn’t be too complex, but could incorporate much of what I’ve learned from interviews. I settled on a wordcloud format to start. I used a couple of different programs (Wordle, Tagxedo) and finally settled on Tagul. I made the wordcloud by reading through the transcripts of my interviews, picking out the key ideas, words and phrases. A lot of people mentioned the same, or highly similar things, so I kept a tally of frequent mentions. I’ve tried to use exact wording from my interviews, but at times I’ve shortened phrases to a word that summarizes them without losing content. (For example, if an interviewee suggested ‘make sure information is specific’, I’ve shortened it simply to ‘specificity’.) I made a couple of different clouds, with emphasis on different things, and played around with coloring and fonts. Here’s an early one:

The font and colors weren’t cutting it. A few more iterations later and I finally settled on this one:

As an educational tool, it’s easy to glance at and take key concepts from. It’s ideally accompanied by a short glossary explaining each of the words and phrases. [I decided to leave out the watermark for spacing reasons, in keeping with the guidelines for the logo.]

For example:

• basics: make sure that documentation is not wholly technical. For new users, it’s important that the basics be explained along with the technical complexities. This makes things much easier to understand and less overwhelming.
• organization: when writing documentation, make sure that it has a clear organization that will be easy to follow for readers. The best way to do this is to follow the Documentation Template, which has pre-established divisions for a logical layout. Of course, the template is not rigid and every aspect is not applicable for all documentation. Just be sure that there is a clear flow of ideas, allow for headings and divisions to separate information so that a reader can easily see the layout of the documentation and find their information.
• simplicity: OpenMRS is used worldwide, and often English is not the first language of users, developers and implementors. Using language that is not overly complicated removes barriers to understanding, and enhances clarity.
• specificity: Especially when writing developer documentation, reference  classes, functions and modules that are necessary for understanding by name, rather than vague mention.
• update: The importance of keeping pages up to date with correct information cannot be overstated, especially in a project where things are constantly changing and being modified and new things are being added.

I’m working on writing up definitions to the rest of the tags in the word cloud, so a short draft of the accompanying glossary will be up soon.

Hopefully, it’s something that will be a useful introduction to OpenMRS documentation and help people think about the key concepts and ideas behind writing module documentation, along with the framework. It also serves as a visual representation of the work and research I’ve been doing that’s hopefully a little more interesting than just another written report.

Phase 1 Draws to a Close

This week, my work bounced all over the place (in the best way possible). I’ve been finishing up the last of my interviews (I still have a few scheduled for next week). It’s great to see all of the information coming together into a very comprehensive overview of user/developer/implementer/contributer interaction with documentation.

This week, I’ve also been sorting through the existing pages of the OpenMRS wiki and roughly sorting them into three categories:

• Extensive work needed: these are the pages that are very out of date, or have very little (if any information) and will need to be heavily worked on to bring up to speed. For these, the module will need to be downloaded and run, and the code will need to be looked at.
• Some work needed: these are the pages that have fairly basic information already, though perhaps not organized and missing some components. These pages don’t need as much work, but maybe still some hands on module-use or a glance at the code to fully update.
• Comprehensive: these pages are great examples of documentation, and have been pointed out by members of the community or follow the requirements they’ve discussed. The HTML form entry page is the best example. Perhaps some minor changes will be needed, but for the most part, these pages are spot-on.

Of course, these divisions are fairly rough and some changes will be made, but for now it’s useful to wrap my head around the documentation that’s out there and the work that needs to be done.

I’ve also been brainstorming the best ways to show of the information I’ve been collecting. I’ve read through a collection of design and graphic design e-books from my school library. I’ve been focusing in on infographics as a useful way to coalesce, synthesize and disseminate what I’ve learned. A simple infographic can go a long way in concisely but precisely showing what’s important about documentation. It can be given to any newcomers who are interested in documentation, as well as existing community members. It’s obviously not the finale of what I’ve been working on, but it is a useful tool that’s a natural byproduct of my work to this point. To this end, I’ve also been familiarizing myself with different types of infographics, and the thought processes behind them; what information? why this information? how should it be displayed? what is the intent? Online tutorials for planning and specific programs (including inkscape) have been on my plate for the week.

To that end, I’ll be putting up a few of my rough drafts in the coming days, as soon as they become blog-worthy.

Module Models

This week I’ve been specifically focusing on modules. Modules in OpenMRS are an integral aspect of the software. They are the customize-able ‘add-ons’ that make OpenMRS so well-suited for so many different users. Module documentation has a lot of problems though, as many of the people I’ve interviewed have pointed out. There’s no really clear formula for writing documentation, so two wiki pages on two different modules might be completely different, and as a result, miss on out on important information. Many modules simply aren’t documented, or have such minimal documentation that they’re still exceptionally difficult to parse through. Documentation is vital for functioning modules: not only for downloading and setting up the modules, but for troubleshooting. Modules aren’t just bonus add-ons to OpenMRS; in many situations, modules are integral components in having a useable software.

From the feedback I’ve gotten on module documentation, here are the core ideas:

• accountability: if developers themselves don’t have the time to write documentation on their modules, there needs to be a way to pass responsibility to someone to ensure that the documentation at the very least, exists. This person or people should also be responsible for making sure module documentation stays up-to-date. For example, if someone is discussing a problem with a module or a unique usage of a module on a mailing list, adding that to the module’s wiki page could be enormously helpful for future developers/users/implementors. Rather than digging through old mailing list logs, all of the information pertaining to the module is displayed on the module’s wiki page. One interesting solution would be to keep an updated list of all the module documentation that needs to be written or updated. Anyone new to OpenMRS wishing to make a contribution could access this list. It would be a great way for them to learn about OpenMRS and how it works, and keep documentation updated for the rest of the community.
• beginner/advanced division: one way to keep documentation accessible for OpenMRS newcomers, but also relevant for more advanced developers would be to divide module documentation into beginner and advanced sections. A beginner section might be a conceptual explanation of the module, with some technicality . A more advanced explanation would go into more technical detail (for example, what are the important classes or functions in the code? how do they interact with one another and code from other modules) and include examples of code. A lot of people said that they themselves, or someone they knew, were scared away from OpenMRS at first because of the complexity of much of the documentation. Making information more accessible to newcomers is important to welcome and facilitate their understanding.
• organization: I’ve spoken of it before, but it’s a testament to the importance of clear and logical organization that it keeps coming up in my interviews. One simple way to provide good organization is by adding a table of contents to the beginning of every module page. At a glance, a person can (hopefully) see exactly where the information they’re searching for might be located. Another aspect of organization that I’ve spoken of is consolidation; keeping information more or less in one place. This ties in to the first point of trying to place vital information from the mailing list on the wiki as well.
• visuals: this is a very simple way to add clarity and information to a module page, and many people have attested that visuals are an excellent way to enhance documentation. There’s a range of possibilities for this, from a flow chart that demonstrates what functions call one another to screenshots of the module at work or during the installation phase.

Here’s an outline of what a module documentation framework could be:

 

The Interviews Continue

This week, I conducted several more interviews with a range of people in OpenMRS. Experiences have ranged hugely from years to just a month. So far, most interviewees have been developers/contributors; but I have implementor/user interviews in the works. Some common themes have started emerging:

• documentation as a part of development: a lot of people have spoken about the unfortunate ease with which documentation becomes outdated. There are a number of reasons for this, but the most obvious is that when a developer makes a change, fixes a bug, uploads a patch, etc. documentation isn’t an inherent step in their programming process. Some developers start a project and then abandon it, leaving half-finished pages that can be very confusing. Somehow, an environment needs to be created that emphasizes the importance of documenting every change that’s made. [There are certainly other reasons for lack of documentation: one person suggested it could be because the OpenMRS community is global, some community members may not be comfortable writing documentation in English.]
• documentation needs ownership: people have suggested another major reason for out of date documentation; lack of central management. There’s no-one who is really leading the documentation project, and no dynamic personality or team to help (and encourage the community to) clean, remove, update and change documentation as needed. Several people have suggested a ‘documentation lead’; someone who can be the OpenMRS documentation caretaker and keep things fresh.
• simplification: for many people, ‘documentation’ in the world of OpenMRS means so many different things that it can be difficult to locate and use information. There’s the wiki, floss manuals, mailing lists, IRC, etc. Many people find it difficult to understand what information goes where, and as a result, find it difficult to navigate through the various sources of documentation. Perhaps consolidation is in order? Or some an organizational system that can better help people navigate the world of documentation. This is important, not only for those seeking information, but for those who want to contribute to documentation as well.
• space for beginners: many people spoke of the difficulty they experienced first getting started in OpenMRS. Though the community is extremely receptive and welcoming, actually loading up and testing out the software can be very difficulty. Many people gave specific suggestions to create a better space for beginners: both implementors and developers. An especially common theme was having more samples, examples, and hands-on activities.

I’ve been asking people as I go if they have any experience with exceptional documentation associated with other projects. So far, a great example has been the w3 schools documentation for learning HTML, CSS, JavaScript, etc. The organization of the website is very logical and easy to follow, the table of contents is very explicit and detailed, navigation is simple, there are plenty of examples, and hands-on activities abound. It’s not exactly a perfect format for OpenMRS, but there are definitely some lessons that can be learned.

In the meantime, I made a rough sketch of the many roles fulfilled by the OpenMRS community, as it can be a little confusing at first glance.

Community (Inter)Views

In the coming week or so, I’ll be conducting interviews with as many people involved in OpenMRS as possible; developers, contributers, implementors, users. The biggest part of the documentation challenge is building something that the community wants to use and contribute to.  Michael and Burke helped develop a set of basic questions as the groundwork for the interviews, and hopefully as stepping-off points for taking advantage of the community as a resource for design:

•  How do you interact with OpenMRS — Are you a developer or contributor? Are you an implementer? A user?
• When you want to find an answer to something OpenMRS, what do you typically do?
• What tools or methods do you generally start with? If that doesn’t work, what do you try next? What happens when you can’t find the answer?
• What do you like about the currently available OpenMRS documentation?
• What do you think could be most improved about OpenMRS documentation? What else?
• What OpenMRS documentation/information resources do you think are missing for people like you?
•  What do you think are the biggest challenges in keeping OpenMRS documentation and information up-to-date? And in keeping people engaged in documenting things they discover/change/update?
•  If we worked on only one part of OpenMRS documentation, what would you want us to improve?

I conducted the first of these interviews today; here’s a very brief summary of the major ideas.

• simplicity, consistency and clarity: in both content and organization, OpenMRS documentation needs to be more streamlined. Difficulty in finding information is just as daunting as difficulty in understanding information, especially for new users.
• keeping things fresh: without a strong central presence in documentation, things become easily outdated and obsolete. Structure might change or information might move to new places with no record, or simply never be updated. This can be very confusing and even offputting, as it might seem that no-one is working in a specific area (when in reality they just might not have updated the documentation or created a new place for the information, or mentioned it on a mailing list but not the wiki, etc.)

I’m excited to see a range of OpenMRS experience, from newbie to veteran. Every perspective should provide valuable insight into addressing the documentation dhallenge. (Readers: if you are interested in participating or know someone who might be, please get in touch! evoeges [at] openmrs [dot] org.)

Here we go!

On Monday (the official start date of OPW) we had a huge brainstorming session for OpenMRS Documentation with my mentors, a few developers and a veteran documentor. The major ideas we tossed back and forth were:

• Information Architecture: an IA is an interesting blend of design and organization which creates groupings for data. It some ways it can be conceptualized as an information tree continually branching as things are grouped more and more precisely. It’s intended to be a concise and intuitive way for people to navigate huge amounts of information- like OpenMRS documentation. At the start of our IA, we divided documentation into two major groups: developers and implementors. Of course the division isn’t always clear-cut, but we’re mainly going to focus on developer documentation, and in such a way that the implementor documentation will be a logical followup. This leads me to the next major point which is:

• Sustainability: one of the most important goals for the summer is not necessarily to create as much output as possible, but to create structure and form that can be continuously used by the OpenMRS community as the project grows and evolves. In the past, documentation projects have been abandoned or forgotten as soon as they ended. We hope that the three month OPW period will be long enough to create a sustainable documentation structure that anyone in the community can continue to use, update and enhance. We’re especially interested in making sure that there’s a place for new documentors who want to become involved in the OpenMRS community. One of the ways we’re going to generate sustainability is by making the role of:

• Documentation Lead: because documentation in OpenMRS has been disorganized and a little unstructured, we’re going to create and define a new role- someone who can really be in charge of documentation. I’m going to be filling these big shoes during OPW, and making sure that the position is one that can be easily continued. This way, documentation can have a face; someone who can help the community create, use, question, update and participate in documentation.

Of course, a lot of fantastic ideas and thoughts came out of the session, but for now these are the most relevant. I’m definitely excited (and a little nervous) to have such a huge part in the process of revamping OpenMRS documentation. Let the adventure begin!